Documentation for Tolk written from scratch #1421
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| For years, FunC was the primary language for TON. | ||
| It gave complete control over the TVM — and if you mastered it, it gave you power. | ||
| But its Lisp-like syntax and functional style made onboarding difficult for many. |
There was a problem hiding this comment.
[HIGH] Second-person pronoun and hype in FunC origin note
The sentence “It gave complete control over the TVM — and if you mastered it, it gave you power.” addresses the reader with “you” and uses hype-style wording (“gave you power”). This violates the guidelines against personal pronouns and marketing-style language in technical documentation. The surrounding narrative can remain factual while removing the second person and hype.
| For years, FunC was the primary language for TON. | |
| It gave complete control over the TVM — and if you mastered it, it gave you power. | |
| But its Lisp-like syntax and functional style made onboarding difficult for many. | |
| For years, FunC was the primary language for TON. | |
| It provided complete control over the TVM for developers who mastered it. | |
| But its Lisp-like syntax and functional style made onboarding difficult for many. |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| obj.toCell({ | ||
| // for `bits128` and similar (a slice under the hood), | ||
| // insert the checks (bits == 128 and refs == 0); | ||
| // turn off to save gas if you guarantee input is valid; | ||
| // `intN` are always validated, it's only for `bitsN` | ||
| skipBitsNValidation: false, // default: false |
There was a problem hiding this comment.
[HIGH] Second-person pronoun in auto-serialization options comment
The inline comment “// turn off to save gas if you guarantee input is valid;” uses “you” to refer to the reader, even though this is explanatory documentation embedded in a code example. This conflicts with the style rule to avoid second-person pronouns in docs, including explanatory comments used for teaching. The meaning can be preserved by referring to conditions on the input instead.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| <Aside | ||
| type="caution" | ||
| > | ||
| This page gives brief descriptions of optimizations performed. | ||
| It is fairly low-level and not required for using Tolk in production. | ||
| </Aside> |
There was a problem hiding this comment.
[HIGH] Throat-clearing “this page/section” openers
Multiple newly added Tolk pages start sections with self-referential “this page/section” sentences instead of leading directly with value, which the style guide flags as throat-clearing. In features/compiler-optimizations.mdx, the caution aside says “This page gives brief descriptions of optimizations performed. It is fairly low-level and not required for using Tolk in production.”; similar constructions appear in features/message-sending.mdx (“This section is intended for experienced users; it discusses terminology.”), syntax/operators.mdx, syntax/structures-fields.mdx, types/list-of-types.mdx, types/overall-serialization.mdx, and types/overall-tvm-stack.mdx. These meta statements add cognitive overhead without conveying new information. Rephrasing them into direct summaries of purpose, audience, or prerequisites keeps the docs concise and aligned with the style rule.
| <Aside | |
| type="caution" | |
| > | |
| This page gives brief descriptions of optimizations performed. | |
| It is fairly low-level and not required for using Tolk in production. | |
| </Aside> | |
| <Aside | |
| type="caution" | |
| > | |
| Summarizes compiler optimizations that affect gas usage. | |
| Intended as low-level background; not required for typical Tolk development. | |
| </Aside> |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
This is not the start of the page, it's an <Aside> element after, placed specifically to attract visual attention
| If you use `RichBounce`, that's the way: | ||
|
|
||
| ```tolk | ||
| fun onBouncedMessage(in: InMessageBounced) { | ||
| val rich = lazy RichBounceBody.fromSlice(in.bouncedBody); | ||
| // handle rich.originalBody | ||
| // use rich.xxx to get exitCode, gasUsed, and so on | ||
| } | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Second-person pronoun in RichBounce handling guidance
The line “If you use RichBounce, that's the way:” addresses the reader directly with “you”. This breaks the rule against using “you/your” in documentation and mixes instructional tone with informal phrasing (“that's the way”). The surrounding section already describes BounceMode variants objectively, so this sentence can be made neutral and descriptive.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| - sometimes, you "send to an address" | ||
| - ... but sometimes, you have workchain + hash | ||
| - sometimes, you compose `StateInit` from code+data | ||
| - ... but sometimes, `StateInit` is a ready cell | ||
| - sometimes, you send a message to basechain | ||
| - ... but sometimes, you use a `MY_WORKCHAIN` constant | ||
| - sometimes, you just attach tons (msg value) | ||
| - ... but sometimes, you also need extra currencies |
There was a problem hiding this comment.
[HIGH] Second-person pronouns in createMessage union examples
The bullet list under “The concept is based on union types” uses multiple second-person constructions such as “sometimes, you 'send to an address'” and “sometimes, you just attach tons (msg value)”. These directly address the reader instead of describing generic behaviors, violating the no-“you/your” rule for documentation text. The list is otherwise explaining patterns of usage and can be written in neutral terms.
| - sometimes, you "send to an address" | |
| - ... but sometimes, you have workchain + hash | |
| - sometimes, you compose `StateInit` from code+data | |
| - ... but sometimes, `StateInit` is a ready cell | |
| - sometimes, you send a message to basechain | |
| - ... but sometimes, you use a `MY_WORKCHAIN` constant | |
| - sometimes, you just attach tons (msg value) | |
| - ... but sometimes, you also need extra currencies |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
There was a problem hiding this comment.
One more comment about "you" in these intentional places:
Even in strict docs of Rust, LLVM, Oracle, etc. it's also quite typical:
- Sometimes you need…
- Sometimes you have…
- etc.
Like here. What's important:
It does not address the reader, contains no imperatives, and avoids direct dialogue.
It is simply a description of a situation, not an interaction with the user.
| Returns `uint256` — a new pseudo-random number. | ||
|
|
||
| Ensure you've called `random.initialize` to make it unpredictable! | ||
|
|
||
| #### random.range(limit) | ||
|
|
||
| Returns `int` — a new pseudo-random integer z in the range `0..limit−1` (or `limit..−1` if negative). | ||
| More precisely, an unsigned random value `x` is generated, then `z := x * limit / 2^256` is computed. | ||
|
|
||
| Ensure you've called `random.initialize` to make it unpredictable! |
There was a problem hiding this comment.
[HIGH] Second-person pronouns in random API notes
Within the random.uint256 and random.range documentation, the line “Ensure you've called random.initialize to make it unpredictable!” appears twice. Both instances directly address the reader with “you've”, which conflicts with the style rule against second-person pronouns in documentation prose. The intent—documenting the need to initialize randomness—can be expressed in a neutral imperative form instead.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| - Do you need validation or just proxy any data as-is? | ||
| - Do you need custom error codes while validating? | ||
| - Do you need to assign it dynamically or just to carry it forward? |
There was a problem hiding this comment.
[HIGH] Second-person pronouns in jetton forward-payload questions
Lines 533–535 ask the reader “Do you need …” three times, directly addressing the reader with “you”. This conflicts with the documentation style rule to avoid second-person pronouns in descriptive guidance. The surrounding section is otherwise neutral and technical, so the second-person phrasing stands out as inconsistent with the rest of the Tolk docs.
| - Do you need validation or just proxy any data as-is? | |
| - Do you need custom error codes while validating? | |
| - Do you need to assign it dynamically or just to carry it forward? |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| If you are migrating from FunC: | ||
|
|
||
| int currentCounter() method_id { | ||
| load_data(); ;; fills global variables | ||
| return ctx_counter; | ||
| } | ||
| ``` | ||
| </details> | ||
| - Look through [benchmarks](https://github.com/ton-blockchain/tolk-bench): notice **30–50% lower gas fees**. | ||
| - Scan the page [Tolk vs FunC](/languages/tolk/from-func/tolk-vs-func) to get the overall picture. | ||
| - Use the [FunC-to-Tolk converter](/languages/tolk/from-func/converter) to migrate existing projects. |
There was a problem hiding this comment.
[HIGH] Second-person pronoun in FunC migration note
The line “If you are migrating from FunC:” explicitly addresses the reader with “you”. This violates the style rule banning second-person pronouns in documentation, even though the rest of the migration guidance is written neutrally. The heading line can be rephrased to describe the migration topic without addressing the reader directly.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
|
I have corrected various misprints you've found. |
There was a problem hiding this comment.
I'm soft-rejecting the current hack because there is a cleaner iteration of it that preserves the color integrity of non-Tolk code, makes all Tolk code blocks apparent with a title, and lets us delete the <TolkHighlight/> component and enable Tolk code highlighting throughout the docs.
See my notes here: https://github.com/ton-org/docs/pull/1421/files#r2572169983
Let's continue discussing the solution to avoid |
- all articles about Tolk type system - get rid of 'you' and 'we' in existing pages
|
The most recent commit has made this PR go over 800 added lines. Please, decrease the size of this pull request or consider splitting it into several smaller requests. Until then, the CI will be marked as failed. UPD: #1504 |
|
A fatal mistake: decided to rebase a branch onto 'main' to have a fresh live demo. |
Yeah, we're experimenting with things, and on top of that, Dependabot (seems to have) pushed an incomplete A couple of points regarding the
Sorry for the possible inconveniences along this bumpy way :) P.S.: Rebases hinder reviews to some degree, because GitHub starts to consider all viewed files as new ones on each rebase. Not to mention the annoying search for comments that were made on files present during some point in the past but were deleted since then. |
|
I think it was already discussed internally, but will write about this here too. @aigerimu is splitting this large PRs into single-article PRs and editing style/language issues, so that we can ensure reviewing it won't take forever. When the process is over, we'll likely close this PR. If we closed it right now, Mintlify would turn off the link in the title of the PR, and we'd prefer to have it for reference. At the moment, I'll move the PR to Draft status, so that it doesn't show up in the filtered list of PRs for daily review. |
|
Mda |
Live demo: https://companyname-a7d5b98e-tolk-docs.mintlify.app/languages/tolk/overview
I have completed a long effort to provide a from-scratch documentation for Tolk.
The previous version, which I had been incrementally maintaining since January, focused on "Tolk vs FunC" differences.
The new one does not require any prior knowledge of FunC. A reader approaches Tolk directly.
The documentation contains many examples, snippets, and real-world cases. Before starting this work, I reviewed the official docs for Rust, Go, and Kotlin — to absorb best practices for presenting a programming language.
What's inside: brief description
Every aspect of the Tolk language is covered:
Additionally, there are two entry-point pages:
The english style used while writing
All pages are written in a short, formal style (as opposed to the PR descriptions I like to create).
Syntax highlighting!
The current documentation lacks of syntax highlighing, because Mintlify does not support custom languages. FunC, Fift, etc. — all of them are rendered as black plain text.
Tolk documentation contains hundreds of snippets and looks too depressive without highlithing.
That's why I implemented a temporary solution — all snippets are now colorful, in both dark and light modes. Just take a look:
All ```tolk snippets are highlighted automatically: no changes in
mdxmarkup is required.The highlighing is client-side, via Prism.js, whose sources are embedded. See
snippets/tolk-highlight.jsx. This component is injected into every/languages/tolk/page.Hopefully, some day, Mintlify will introduce native server-side highlighing. Then, we can discuss across coloring. I fine-tuned grammar and palette the way I prefer it (for example, structures and variables have different colors, because of the capital letter). The current VS Code
tmLanguagefile is not suitable for this — it must be updated.For reviewers
If anyone decides to review all the text in this PR, keep this in mind:
...three dots in code snippets are intentional; small snippets are not meant to be copy-pasted — they demonstrate a specific featureAbout merging this PR
Git history is split into multiple sensible commits. For instance, a syntax highlighter is a separate commit.
It's up to you whether to "Squash and merge" all changes into a single commit or to "Rebase and merge" to preserve Git history. I do not see any disadvantages in having multiple commits.
For future changes
If anyone plans to modify the contents in the Tolk documentation, please remember:
The documentation in numbers
All together, the new Tolk documentation contains:
I invested ~200 hours developing the text and picking every word — exactly 14 days, about 14 hours a day.
I hope that, cumulatively, this documentation will save noticeably more time for all TON developers.
Closes #1136
Closes #1473
Closes #1114
Closes #73
Closes #1128
Live demo: https://companyname-a7d5b98e-tolk-docs.mintlify.app/languages/tolk/overview